<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- ../src/examples/spinboxes.qdoc -->
<head>
  <title>Spin Boxes Example</title>
    <style type="text/css">h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { color: black; }</style>
</head>
<body>
<h1 class="title">Spin Boxes Example<br /><span class="subtitle"></span>
</h1>
<p>The Spin Boxes example shows how to use the many different types of spin boxes available in Qt, from a simple QSpinBox widget to more complex editors like the QDateTimeEdit widget.</p>
<p align="center"><img src="classpath:com/trolltech/images/spinboxes-example.png" /></p><p>The example consists of a single <tt>Window</tt> class that is used to display the different spin box-based widgets available with Qt.</p>
<a name="window-class-implementation"></a>
<h2>Window Class Implementation</h2>
<p>The <tt>Window</tt> class inherits QWidget and contains two slots that are used to provide interactive features:</p>
<pre>    public class SpinBoxes extends QWidget {
        private QDateTimeEdit meetingEdit;
        private QDoubleSpinBox doubleSpinBox;
        private QDoubleSpinBox priceSpinBox;
        private QDoubleSpinBox scaleSpinBox;
        private QGroupBox spinBoxesGroup;
        private QGroupBox editsGroup;
        private QGroupBox doubleSpinBoxesGroup;
        private QLabel meetingLabel;</pre>
<p>Private methods (shown later) are used to set up each type of spin box in the window. We use variables to keep track of various widgets so that they can be reconfigured when required.</p>
<p>The constructor simply calls private methods to set up the different types of spin box used in the example, and places each group in a layout:</p>
<pre>        public SpinBoxes() {
            this(null);
        }</pre>
<p>We use the layout to manage the arrangement of the window's child widgets, and change the window title.</p>
<p>The <tt>createSpinBoxes()</tt> method constructs a QGroupBox and places three QSpinBox widgets inside it with descriptive labels to indicate the types of input they expect.</p>
<pre>            createSpinBoxes();
            createDateTimeEdits();
            createDoubleSpinBoxes();

            QHBoxLayout layout = new QHBoxLayout();
            layout.addWidget(spinBoxesGroup);
            layout.addWidget(editsGroup);
            layout.addWidget(doubleSpinBoxesGroup);
            setLayout(layout);

            setWindowTitle(tr(&quot;Spin Boxes&quot;));

            setWindowIcon(new QIcon(&quot;classpath:com/trolltech/classpath:com/trolltech/images/qt-logo.png&quot;));
        }

        public void createSpinBoxes() {
            spinBoxesGroup = new QGroupBox(tr(&quot;Spinboxes&quot;));

            QLabel integerLabel = new QLabel(String.format(tr(&quot;Enter a value between %1$d and %2$d:&quot;), -20, 20));
            QSpinBox integerSpinBox = new QSpinBox();
            integerSpinBox.setRange(-20, 20);
            integerSpinBox.setSingleStep(1);
            integerSpinBox.setValue(0);</pre>
<p>The first spin box shows the simplest way to use QSpinBox. It accepts values from -20 to 20, the current value can be increased or decreased by 1 with either the arrow buttons or <b>Up</b> and <b>Down</b> keys, and the default value is 0.</p>
<p>The second spin box uses a larger step size and displays a suffix to provide more information about the type of data the number represents:</p>
<pre>            QLabel zoomLabel = new QLabel(String.format(tr(&quot;Enter a zoom value between %1$d and %2$d:&quot;), 0, 1000));
            QSpinBox zoomSpinBox = new QSpinBox();
            zoomSpinBox.setRange(0, 1000);
            zoomSpinBox.setSingleStep(10);
            zoomSpinBox.setSuffix(&quot;%&quot;);
            zoomSpinBox.setSpecialValueText(tr(&quot;Automatic&quot;));
            zoomSpinBox.setValue(100);</pre>
<p>This spin box also displays a special value instead of the minimum value defined for it. This means that it will never show <b>0%</b>, but will display <b>Automatic</b> when the minimum value is selected.</p>
<p>The third spin box shows how a prefix can be used:</p>
<pre>            QLabel priceLabel = new QLabel(String.format(tr(&quot;Enter a price between %1$d and %2$d:&quot;), 0, 999));
            QSpinBox priceSpinBox = new QSpinBox();
            priceSpinBox.setRange(0, 999);
            priceSpinBox.setSingleStep(1);
            priceSpinBox.setPrefix(&quot;$&quot;);
            priceSpinBox.setValue(99);</pre>
<p>For simplicity, we show a spin box with a prefix and no suffix. It is also possible to use both at the same time.</p>
<pre>            QVBoxLayout spinBoxLayout = new QVBoxLayout();
            spinBoxLayout.addWidget(integerLabel);
            spinBoxLayout.addWidget(integerSpinBox);
            spinBoxLayout.addWidget(zoomLabel);
            spinBoxLayout.addWidget(zoomSpinBox);
            spinBoxLayout.addWidget(priceLabel);
            spinBoxLayout.addWidget(priceSpinBox);
            spinBoxesGroup.setLayout(spinBoxLayout);
        }</pre>
<p>The rest of the method sets up a layout for the group box and places each of the widgets inside it.</p>
<p>The <tt>createDateTimeEdits()</tt> method constructs another group box with a selection of spin boxes used for editing dates and times.</p>
<pre>        public void createDateTimeEdits() {
            editsGroup = new QGroupBox(tr(&quot;Date and time spin boxes&quot;));

            QLabel dateLabel = new QLabel();
            QDateEdit dateEdit = new QDateEdit(QDate.currentDate());
            dateEdit.setDateRange(new QDate(2005, 1, 1), new QDate(2010, 12, 31));
            dateLabel.setText(String.format(tr(&quot;Appointment date (between %1$s and %2$s):&quot;),
                                            dateEdit.minimumDate().toString(Qt.DateFormat.ISODate),
                                            dateEdit.maximumDate().toString(Qt.DateFormat.ISODate)));</pre>
<p>The first spin box is a QDateEdit widget that is able to accept dates within a given range specified using QDate values. The arrow buttons and <b>Up</b> and <b>Down</b> keys can be used to increase and decrease the values for year, month, and day when the cursor is in the relevant section.</p>
<p>The second spin box is a QTimeEdit widget:</p>
<pre>            QLabel timeLabel = new QLabel();
            QTimeEdit timeEdit = new QTimeEdit(QTime.currentTime());
            timeEdit.setTimeRange(new QTime(9, 0, 0, 0), new QTime(16, 30, 0, 0));
            timeLabel.setText(String.format(tr(&quot;Appointment time (between %1$s and %2$s):&quot;),
                                            timeEdit.minimumTime().toString(Qt.DateFormat.ISODate),
                                            timeEdit.maximumTime().toString(Qt.DateFormat.ISODate)));</pre>
<p>Acceptable values for the time are defined using QTime values.</p>
<p>The third spin box is a QDateTimeEdit widget that can display both date and time values, and we place a label above it to indicate the range of allowed times for a meeting. These widgets will be updated when the user changes a format string.</p>
<pre>            meetingLabel = new QLabel();
            meetingEdit = new QDateTimeEdit(QDateTime.currentDateTime());</pre>
<p>The format string used for the date time editor, which is also shown in the string displayed by the label, is chosen from a set of strings in a combobox:</p>
<pre>            QLabel formatLabel = new QLabel(tr(&quot;Format string for the meeting date and time:&quot;));
            QComboBox formatComboBox = new QComboBox();
            formatComboBox.addItem(&quot;yyyy-MM-dd hh:mm:ss (zzz 'ms')&quot;);
            formatComboBox.addItem(&quot;hh:mm:ss MM/dd/yyyy&quot;);
            formatComboBox.addItem(&quot;hh:mm:ss dd/MM/yyyy&quot;);
            formatComboBox.addItem(&quot;hh:mm:ss&quot;);
            formatComboBox.addItem(&quot;hh:mm ap&quot;);
            formatComboBox.activated.connect(this, &quot;setFormatString(String)&quot;);</pre>
<p>A signal from this combobox is connected to a slot in the <tt>Window</tt> class (shown later).</p>
<pre>            QVBoxLayout editsLayout = new QVBoxLayout();
            editsLayout.addWidget(dateLabel);
            editsLayout.addWidget(dateEdit);
            editsLayout.addWidget(timeLabel);
            editsLayout.addWidget(timeEdit);
            editsLayout.addWidget(meetingLabel);
            editsLayout.addWidget(meetingEdit);
            editsLayout.addWidget(formatLabel);
            editsLayout.addWidget(formatComboBox);
            editsGroup.setLayout(editsLayout);
        }</pre>
<p>Each child widget of the group box in placed in a layout.</p>
<p>The <tt>setFormatString()</tt> slot is called whenever the user selects a new format string in the combobox. The display format for the QDateTimeEdit widget is set using the raw string passed by the signal:</p>
<pre>        public void setFormatString(String formatString) {
            meetingEdit.setDisplayFormat(formatString);</pre>
<p>Depending on the visible sections in the widget, we set a new date or time range, and update the associated label to provide relevant information for the user:</p>
<pre>            if (meetingEdit.displayedSections().isSet(QDateTimeEdit.Section.DateSections_Mask)) {
                meetingEdit.setDateRange(new QDate(2004, 11, 1), new QDate(2005, 11, 30));
                meetingLabel.setText(String.format(tr(&quot;Meeting date (between %1$s and %2$s):&quot;),
                                                   meetingEdit.minimumDate().toString(Qt.DateFormat.ISODate), meetingEdit.maximumDate().toString(Qt.DateFormat.ISODate)));
            } else {
                meetingEdit.setTimeRange(new QTime(0, 7, 20, 0), new QTime(21, 0, 0, 0));
                meetingLabel.setText(String.format(tr(&quot;Meeting time (between %1$s and %2$s):&quot;), meetingEdit.minimumTime().toString(Qt.DateFormat.ISODate), meetingEdit.maximumTime().toString(Qt.DateFormat.ISODate)));
            }
        }</pre>
<p>When the format string is changed, there will be an appropriate label and entry widget for dates, times, or both types of input.</p>
<p>The <tt>createDoubleSpinBoxes()</tt> method constructs three spin boxes that are used to input double-precision floating point numbers:</p>
<pre>        public void createDoubleSpinBoxes() {
            doubleSpinBoxesGroup = new QGroupBox(tr(&quot;Double precision spinboxes&quot;));

            QLabel precisionLabel = new QLabel(tr(&quot;Number of decimal places to show:&quot;));
            QSpinBox precisionSpinBox = new QSpinBox();
            precisionSpinBox.setRange(0, 13);
            precisionSpinBox.setValue(2);</pre>
<p>Before the QDoubleSpinBox widgets are constructed, we create a spin box to control how many decimal places they show. By default, only two decimal places are shown in the following spin boxes, each of which is the equivalent of a spin box in the group created by the <tt>createSpinBoxes()</tt> method.</p>
<p>The first double spin box shows a basic double-precision spin box with the same range, step size, and default value as the first spin box in the <tt>createSpinBoxes()</tt> method:</p>
<pre>            QLabel doubleLabel = new QLabel(String.format(tr(&quot;Enter a value between %1$d and %2$d:&quot;), -20, 20));
            doubleSpinBox = new QDoubleSpinBox();
            doubleSpinBox.setRange(-20.0, 20.0);
            doubleSpinBox.setSingleStep(1.0);
            doubleSpinBox.setValue(0.0);</pre>
<p>However, this spin box also allows non-integer values to be entered.</p>
<p>The second spin box displays a suffix and shows a special value instead of the minimum value:</p>
<pre>            QLabel scaleLabel = new QLabel(String.format(tr(&quot;Enter a scale factor between %1$d and %2$d:&quot;), 0, 1000));
            scaleSpinBox = new QDoubleSpinBox();
            scaleSpinBox.setRange(0.0, 1000.0);
            scaleSpinBox.setSingleStep(10.0);
            scaleSpinBox.setSuffix(&quot;%&quot;);
            scaleSpinBox.setSpecialValueText(tr(&quot;No scaling&quot;));
            scaleSpinBox.setValue(100.0);</pre>
<p>The third spin box displays a prefix instead of a suffix:</p>
<pre>            QLabel priceLabel = new QLabel(String.format(tr(&quot;Enter a price between %1$d and %2$d:&quot;), 0, 1000));
            priceSpinBox = new QDoubleSpinBox();
            priceSpinBox.setRange(0.0, 1000.0);
            priceSpinBox.setSingleStep(1.0);
            priceSpinBox.setPrefix(&quot;$&quot;);
            priceSpinBox.setValue(99.99);

            precisionSpinBox.valueChanged.connect(this, &quot;changePrecision(int)&quot;);</pre>
<p>We connect the QSpinBox widget that specifies the precision to a slot in the <tt>Window</tt> class.</p>
<pre>            QVBoxLayout spinBoxLayout = new QVBoxLayout();
            spinBoxLayout.addWidget(precisionLabel);
            spinBoxLayout.addWidget(precisionSpinBox);
            spinBoxLayout.addWidget(doubleLabel);
            spinBoxLayout.addWidget(doubleSpinBox);
            spinBoxLayout.addWidget(scaleLabel);
            spinBoxLayout.addWidget(scaleSpinBox);
            spinBoxLayout.addWidget(priceLabel);
            spinBoxLayout.addWidget(priceSpinBox);
            doubleSpinBoxesGroup.setLayout(spinBoxLayout);
        }</pre>
<p>The rest of the method places each of the widgets into a layout for the group box.</p>
<p>The <tt>changePrecision()</tt> slot is called when the user changes the value in the precision spin box:</p>
<pre>        public void changePrecision(int decimals) {
            doubleSpinBox.setDecimals(decimals);
            scaleSpinBox.setDecimals(decimals);
            priceSpinBox.setDecimals(decimals);
        }</pre>
<p>This method simply uses the integer supplied by the signal to specify the number of decimal places in each of the QDoubleSpinBox widgets. Each one of these will be updated automatically when their decimals property is changed.</p>
<p>Finally, we provide a <tt>main()</tt> method to create and show the <tt>SpinBoxes</tt> widget when the example is run:</p>
<pre>        public static void main(String args[]) {
            QApplication.initialize(args);

            SpinBoxes spinBoxes = new SpinBoxes();
            spinBoxes.show();

            QApplication.exec();
        }
    }</pre>
</body>
</html>
